============================================================
  IDAT ACADEMY API - ENDPOINTS & URL DOCUMENTATION
  Base URL: https://idat.ng/api
  Last Updated: 2026-07-30
============================================================

------------------------------------------------------------
1. AUTHENTICATION
------------------------------------------------------------
All endpoints require authentication except health check & login.

Methods:
  A. API Key
     Header: X-API-Key: idat_live_k8x2m9p4q7w1e5r3t6y0u
     OR Query: ?api_key=idat_live_k8x2m9p4q7w1e5r3t6y0u
     Access: Admin-level (full access)

  B. Bearer Token (obtained from /login)
     Header: Authorization: Bearer <token>
     Access: Based on account_type (admin, staff, student) and role

------------------------------------------------------------
2. ROLE-BASED ACCESS CONTROL (RBAC)
------------------------------------------------------------
The API uses three account types with the following hierarchy:

  admin   - Full access to all resources
  staff   - Access based on role (tutor, staff, manager, etc.)
  student - Access limited to own data only

Admin users bypass all permission checks.
Staff/tutor users can manage their own teaching resources.
Student users can only view/manage their own data.

------------------------------------------------------------
3. SYSTEM & AUTH ENDPOINTS
------------------------------------------------------------

  GET  /api
       Health check / API status
       Auth: No
       Response: {"status":"ok","version":"1.0.0","time":"..."}

  GET  /api/health
       Health check (alias)
       Auth: No

  POST /api/login
       Authenticate user
       Auth: No
       Body: { "email": "...", "password": "...", "portal": "student|tutor|admin|any" }
       Response: { "access_token": "...", "token_type": "Bearer", "expires_in": 2592000, "account_type": "...", "role": "...", "user": {...} }
       Note: Response includes account_type (admin/staff/student) and role for frontend routing

  POST /api/logout
       Revoke current Bearer token
       Auth: Bearer token (any authenticated user)
       Response: { "message": "Logged out successfully." }

------------------------------------------------------------
4. COURSES
------------------------------------------------------------

  GET  /api/courses
       List active courses (paginated, filterable)
       Roles: All (authenticated)
       Query: page, per_page, all, category, status, search, learning_mode, sort, tutor_id
       Response: { "data": [...], "pagination": {...} }

  GET  /api/courses/{id}
       Single course by ID or slug (includes modules + stats)
       Roles: All (authenticated)

------------------------------------------------------------
5. STUDENTS
------------------------------------------------------------

  GET  /api/students
       List students (paginated, searchable)
       Roles: admin, staff
       Query: page, per_page, all, status, search, application_id

  GET  /api/students/{id}
       Single student with enrollments + stats
       Roles: admin, staff, or own student profile

  PUT  /api/students/{id}
       Update student profile
       Roles: admin, or own student profile
       Body: { "first_name", "last_name", "phone", "gender", "state", "lga", "address", "photo", ... }

------------------------------------------------------------
6. ENROLLMENTS
------------------------------------------------------------

  GET  /api/enrollments
       List enrollments (paginated, filterable)
       Roles: admin, staff. Students see only their own enrollments.
       Query: page, per_page, student_id, course_id, status

  GET  /api/enrollments/{id}
       Single enrollment with course progress
       Roles: admin, staff

  POST /api/enrollments
       Enroll a student in a course
       Roles: admin, staff
       Body: { "student_id": "...", "course_id": "..." }
       Response: 201

  PUT  /api/enrollments/{id}
       Update enrollment status
       Roles: admin, staff
       Body: { "status": "enrolled|completed|dropped" }

------------------------------------------------------------
7. LESSONS
------------------------------------------------------------

  GET  /api/lessons
       List lessons (paginated, filterable)
       Roles: All (authenticated)
       Query: page, per_page, course_id, search, tutor_id, module_id

  GET  /api/lessons/{id}
       Single lesson
       Roles: All (authenticated)

  POST /api/lessons
       Create a new lesson
       Roles: admin, staff
       Body: { "course_id", "staff_id"/"tutor_id", "title", "description", "file_path", "file_type", "module_id" }
       Response: 201

  PUT  /api/lessons/{id}
       Update lesson fields
       Roles: admin, staff

  DELETE /api/lessons/{id}
       Delete a lesson
       Roles: admin, staff

------------------------------------------------------------
8. ASSIGNMENTS
------------------------------------------------------------

  GET  /api/assignments
       List assignments (filterable, paginated)
       Roles: All (authenticated)
       Query: page, per_page, course_id, search, tutor_id, module_id

  GET  /api/assignments/{id}
       Single assignment with submission stats
       Roles: All (authenticated)

------------------------------------------------------------
9. SUBMISSIONS
------------------------------------------------------------

  GET  /api/submissions
       List submissions (paginated, filterable)
       Roles: admin, staff. Students see only their own submissions.
       Query: page, per_page, student_id, assignment_id, graded

  GET  /api/submissions/{id}
       Single submission
       Roles: admin, staff

  POST /api/submissions
       Submit an assignment
       Roles: admin, staff, student
       Body: { "assignment_id", "student_id", "file_path", "typed_response" }
       Response: 201

  PUT  /api/submissions/{id}
       Grade/update a submission
       Roles: admin, staff
       Body: { "score", "feedback", "graded_by" }

------------------------------------------------------------
10. PAYMENTS
------------------------------------------------------------

  GET  /api/payments
       List payments (paginated, filterable)
       Roles: admin. Students see only their own payments.
       Query: page, per_page, student_id, status

  GET  /api/payments/{id}
       Single payment
       Roles: admin

  POST /api/payments
       Record a new payment
       Roles: admin, student
       Body: { "amount", "student_id"/"application_id", "proof_file", "status", "verified_by" }
       Response: 201

  PUT  /api/payments/{id}
       Verify or reject a payment
       Roles: admin
       Body: { "status": "pending|confirmed|rejected", "verified_by" }

------------------------------------------------------------
11. CERTIFICATES
------------------------------------------------------------

  GET  /api/certificates
       List certificates (paginated, filterable)
       Roles: admin. Students see only their own certificates.
       Query: page, per_page, student_id, course_id

  GET  /api/certificates/{id}
       Single certificate
       Roles: admin

  POST /api/certificates
       Issue a new certificate
       Roles: admin
       Body: { "student_id", "course_id", "certificate_number", "file_path", "issue_date" }
       Response: 201

------------------------------------------------------------
12. NOTIFICATIONS
------------------------------------------------------------

  GET  /api/notifications
       List notifications (paginated, filterable)
       Roles: admin. Students see only their own notifications.
       Query: page, per_page, student_id, type, is_read, scheduled

  GET  /api/notifications/{id}
       Single notification
       Roles: admin

  POST /api/notifications
       Create/schedule notifications
       Roles: admin, staff
       Body: { "title", "type", "message", "scheduled_at", "student_id"/"student_ids"/"send_to_all" }
       Response: 201

  PUT  /api/notifications/{id}
       Mark notification as read
       Roles: admin
       Body: { "is_read": 1 }

  DELETE /api/notifications/{id}
       Delete a notification
       Roles: admin

------------------------------------------------------------
13. TUTORS
------------------------------------------------------------

  GET  /api/tutors
       List tutors (staff with role=tutor)
       Roles: All (authenticated)
       Query: page, per_page, status, search

  GET  /api/tutors/{id}
       Single tutor with courses + stats
       Roles: All (authenticated)

------------------------------------------------------------
14. APPLICATIONS
------------------------------------------------------------

  GET  /api/applications
       List applications (paginated, filterable)
       Roles: admin, staff
       Query: page, per_page, status, search

  GET  /api/applications/{id}
       Single application with reviewer info
       Roles: admin, staff

  POST /api/applications
       Submit a new application
       Roles: No auth required
       Body: { "first_name", "last_name", "email", "phone", "gender", "state", "lga", "address", "preferred_courses", "preferred_mode", ... }
       Response: 201

  PUT  /api/applications/{id}
       Approve/reject an application
       Roles: admin, staff
       Body: { "status": "pending|approved|rejected", "reviewed_by" }

------------------------------------------------------------
15. STAFF
------------------------------------------------------------

  GET  /api/staff
       List staff (paginated, filterable)
       Roles: admin
       Query: page, per_page, all, status, role, search, email

  GET  /api/staff/{id}
       Single staff member
       Roles: admin, or own staff profile

  POST /api/staff
       Create a new staff member
       Roles: admin
       Body: { "first_name", "last_name", "email", "password", "role", "phone", "bio", "photo", "salary" }
       Response: 201

  PUT  /api/staff/{id}
       Update staff member
       Roles: admin, or own staff profile

  DELETE /api/staff/{id}
       Delete a staff member
       Roles: admin

------------------------------------------------------------
16. BRANCHES
------------------------------------------------------------

  GET  /api/branches
       List branches (filterable by status)
       Roles: All (authenticated)
       Query: status, all

  GET  /api/branches/{id}
       Single branch
       Roles: All (authenticated)

  POST /api/branches
       Create a new branch
       Roles: admin
       Body: { "name", "address", "city", "state", "phone", "email", "latitude", "longitude", "is_primary", "status" }
       Response: 201

  PUT  /api/branches/{id}
       Update branch
       Roles: admin

  DELETE /api/branches/{id}
       Delete a branch
       Roles: admin

------------------------------------------------------------
17. TESTIMONIALS
------------------------------------------------------------

  GET  /api/testimonials
       List testimonials (filterable)
       Roles: All (authenticated)
       Query: status

  GET  /api/testimonials/{id}
       Single testimonial
       Roles: All (authenticated)

  POST /api/testimonials
       Submit a testimonial
       Roles: All (authenticated)
       Body: { "name", "message", "rating" }
       Response: 201

  PUT  /api/testimonials/{id}
       Approve/reject a testimonial
       Roles: admin
       Body: { "status": "pending|approved|rejected" }

  DELETE /api/testimonials/{id}
       Delete a testimonial
       Roles: admin

------------------------------------------------------------
18. GALLERY
------------------------------------------------------------

  GET  /api/gallery
       List gallery images (filterable)
       Roles: All (authenticated)
       Query: category

  GET  /api/gallery/{id}
       Single gallery image
       Roles: All (authenticated)

  POST /api/gallery
       Upload an image record
       Roles: admin
       Body: { "image_path", "title", "category", "uploaded_by" }
       Response: 201

  DELETE /api/gallery/{id}
       Delete a gallery image
       Roles: admin

------------------------------------------------------------
19. ANNOUNCEMENTS
------------------------------------------------------------

  GET  /api/announcements
       List announcements (filterable)
       Roles: All (authenticated)
       Query: tutor_id, course_id

  GET  /api/announcements/{id}
       Single announcement
       Roles: All (authenticated)

  POST /api/announcements
       Create an announcement
       Roles: admin, staff
       Body: { "tutor_id", "title", "message", "course_id", "recipient_count" }
       Response: 201

------------------------------------------------------------
20. CONTACT MESSAGES
------------------------------------------------------------

  GET  /api/contact_messages
       List contact messages (filterable)
       Roles: admin
       Query: is_read

  GET  /api/contact_messages/{id}
       Single contact message
       Roles: admin

  POST /api/contact_messages
       Submit a contact message
       Roles: No auth required
       Body: { "name", "email", "message", "phone", "subject" }
       Response: 201

  PUT  /api/contact_messages/{id}
       Mark message as read
       Roles: admin
       Body: { "is_read": 1 }

  DELETE /api/contact_messages/{id}
       Delete a contact message
       Roles: admin

------------------------------------------------------------
21. PAYROLL
------------------------------------------------------------

  GET  /api/payroll
       List payroll records (filterable)
       Roles: admin. Staff see only their own records.
       Query: all, staff_id, status, search

  GET  /api/payroll/{id}
       Single payroll record
       Roles: admin

  POST /api/payroll
       Create a payroll record
       Roles: admin
       Body: { "staff_id", "amount", "pay_period_start", "pay_period_end", "payment_date", "status", "notes" }
       Response: 201

  PUT  /api/payroll/{id}
       Update payroll record
       Roles: admin

  DELETE /api/payroll/{id}
       Delete a payroll record
       Roles: admin

------------------------------------------------------------
22. COURSE OUTLINES
------------------------------------------------------------

  GET  /api/course_outlines
       List outlines (filterable)
       Roles: All (authenticated)
       Query: all, course_id, tutor_id, status

  GET  /api/course_outlines/{id}
       Single outline
       Roles: All (authenticated)

  POST /api/course_outlines
       Create a course outline
       Roles: admin, staff
       Body: { "course_id", "tutor_id", "title", "outline_content", "description", "objectives", "status" }
       Response: 201

  PUT  /api/course_outlines/{id}
       Update outline
       Roles: admin, staff

  DELETE /api/course_outlines/{id}
       Delete an outline
       Roles: admin, staff

------------------------------------------------------------
23. TUTOR REPORTS
------------------------------------------------------------

  GET  /api/tutor_reports
       List reports (filterable)
       Roles: admin, staff. Tutors see only their own reports.
       Query: all, tutor_id, course_id, report_type

  GET  /api/tutor_reports/{id}
       Single report
       Roles: admin

  POST /api/tutor_reports
       Create a tutor report
       Roles: admin, staff
       Body: { "tutor_id", "title", "content", "course_id", "report_type" }
       Response: 201

  PUT  /api/tutor_reports/{id}
       Update report
       Roles: admin, staff

  DELETE /api/tutor_reports/{id}
       Delete a report
       Roles: admin, staff

------------------------------------------------------------
24. CLASS ASSESSMENTS
------------------------------------------------------------

  GET  /api/class_assessments
       List assessments (paginated, filterable)
       Roles: admin, staff. Students see only their own scores.
       Query: page, per_page, course_id, staff_id, student_id

  GET  /api/class_assessments/{id}
       Single assessment with student scores
       Roles: admin, staff

  POST /api/class_assessments
       Create a new assessment
       Roles: admin, staff
       Body: { "course_id", "staff_id", "title", "description", "max_score", "assessment_date" }
       Response: 201

  POST /api/class_assessments/{id}/scores
       Add/update a student's score
       Roles: admin, staff
       Body: { "student_id", "score" }

  PUT  /api/class_assessments/{id}
       Update assessment fields
       Roles: admin, staff

  DELETE /api/class_assessments/{id}
       Delete an assessment
       Roles: admin, staff

------------------------------------------------------------
25. ATTENDANCE
------------------------------------------------------------

  GET  /api/attendance
       List staff attendance records
       Roles: admin, staff. Staff see only their own records.
       Query: staff_id, date, open

  POST /api/attendance/qr
       Generate/replace staff QR credential
       Roles: admin
       Body: { "staff_id" }
       Response: 201

  POST /api/attendance/scan
       Clock staff in/out via QR token or admin override
       Roles: admin, staff
       Body: { "action": "clock_in|clock_out", "qr_token" OR "staff_id"+"method":"admin", "course_id", "branch_id", "notes" }

------------------------------------------------------------
26. STATISTICS / DASHBOARD
------------------------------------------------------------

  GET  /api/stats
       Platform-wide dashboard statistics
       Roles: admin
       Response: { "data": { "students": {...}, "courses": {...}, "enrollments": {...}, "tutors": {...}, "payments": {...}, "applications": {...}, "assignments": {...}, "certificates": {...}, "notifications": {...} } }

------------------------------------------------------------
27. SETTINGS
------------------------------------------------------------

  GET  /api/settings
       List all settings (filter by keys)
       Roles: admin
       Query: keys (comma-separated)

  GET  /api/settings/{key}
       Single setting by key
       Roles: admin

  POST /api/settings
       Create or update setting(s)
       Roles: admin
       Body: { "setting_key": "...", "setting_value": "..." } OR { "settings": { "key1": "val1", "key2": "val2" } }

------------------------------------------------------------
28. RESPONSE FORMAT
------------------------------------------------------------
All responses are JSON with Content-Type: application/json.

Paginated endpoints return:
{
  "data": [...],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total": 100,
    "last_page": 5
  }
}

Error format:
{
  "error": "Error message",
  "status": 400
}

------------------------------------------------------------
29. QUICK START GUIDE
------------------------------------------------------------

Step 1: Check server is alive (no auth needed)
  GET https://idat.ng/api

Step 2: Login to get token
  POST https://idat.ng/api/login
  Content-Type: application/json
  Body: { "email": "user@example.com", "password": "yourpassword" }

Step 3: Use token for all other requests
  GET https://idat.ng/api/students
  Authorization: Bearer <token_from_step_2>

  OR use API Key directly:
  GET https://idat.ng/api/students
  X-API-Key: idat_live_k8x2m9p4q7w1e5r3t6y0u

------------------------------------------------------------
30. RATE LIMITING
------------------------------------------------------------
60 requests per minute per IP address.
